package org.estela.classifiers;

import java.io.Externalizable;

import org.estela.ml.dataset.Attribute;
import org.estela.ml.dataset.DataSet;
import org.estela.ml.dataset.Instance;
import org.estela.ml.dataset.InvalidInstanceException;



/**
 * All schemes for numeric or nominal prediction implement this interface.
 * @version 1.00
 * @date Apr 23, 2006
 * @author <a href="mailto:akantek@nyse.com">Antonio Kantek</a>
 */
public interface Classifier extends Cloneable, Externalizable {
	
	/**
	 * Generates the classifier (initialize all parameters).
	 * @param trainingSet The training set.
	 * @param classAttribute The class attribute.
	 * @throws UnsupportedClassAttribute If the class attribute is not supported
	 * by this classifier.
	 */
	void build(DataSet trainingSet, int classAttributeIndex) throws UnsupportedClassAttribute;
	
	/**
	 * Classifies the instance passed as parameter.
	 * @param instance The instance to be classified.
	 * @return Returns the predicted most likely class for the instance or 
	 * <code>Double.NaN</code> if no prediction is made.
     * @exception InvalidInstanceException If the instance to be classified is 
     * not compatible with the training set used to build this classifier.
	 */
	double classify(Instance instance) throws InvalidInstanceException;
	
	/**
	 * Predict the class memberships for a given instance. If an instance is 
	 * unclassified, the returned array elements must be all zero. If the class
	 * is numeric, the array must consist of only one element, which contains
	 * the predicted value.
	 * @param instance The instance to be classified.
	 * @return Returns an array containing the estimated memebership 
	 * probabilities of the test instance in each class or the numeric 
	 * prediction.
     * @exception InvalidInstanceException If the instance to be classified is 
     * not compatible with the training set used to build this classifier.
	 */
	double[] distribution(Instance instance) throws InvalidInstanceException;
	
	/**
	 * @return Returns the attributes.
	 */
	Attribute[] getAttributes();

	/**
	 * @return Returns the classAttribute.
	 */
	Attribute getClassAttribute();

	/**
	 * @return Returns the classAttributeIndex.
	 */
	int getClassAttributeIndex();
}
